Interrupt 21h Function 714Eh 

Searches a directory for the first file or directory whose name and attributes match the specified name and attributes.

mov ax, 714Eh             ; Find First File

mov ch, MustMatchAttrs    ; see below

mov cl, SearchAttrs       ; see below

mov dx, seg Filename      ; see below

mov ds, dx

mov dx, offset Filename

mov di, seg FindData      ; see below

mov es, di

mov di, offset FindData

mov si, DateTimeFormat    ; see below

int 21h

 

jc  error

mov [Handle], ax          ; search handle

mov [ConversionCode], cx  ; Unicode to OEM/ANSI conversion OK?

 

Parameters

MustMatchAttrs

Additional filter on the attributes specified in SearchAttrs. This parameter can be a combination of these values:

_A_NORMAL (0000h)

 

 

The file can be read from or written to. This value is valid only if used alone.

 

_A_RDONLY (0001h)

 

 

The file can be read from, but not written to.

 

_A_HIDDEN (0002h)

 

 

The file is hidden and does not appear in an ordinary directory listing.

 

_A_SYSTEM (0004h)

 

 

The file is part of the operating system or is used exclusively by it.

 

_A_VOLID (0008h)

 

 

The name specified by Filename is used as the volume label for the current medium.

 

_A_SUBDIR (0010h)

 

 

The name specified by Filename is used as a directory, not a file.

 

_A_ARCH (0020h)

 

 

The file is an archive file. Applications use this value to mark files for backup or removal.

 

 

SearchAttrs

File attributes to search for. This parameter can be a combination of these values:

_A_NORMAL (0000h)

_A_RDONLY (0001h)

_A_HIDDEN (0002h)

_A_SYSTEM (0004h)

_A_VOLID (0008h)

_A_SUBDIR (0010h)

_A_ARCH (0020h)

 

Filename

Address of a null-terminated string specifying the name of the file or directory to search for. The name, which must be a valid filename or directory name, can include the  *  and  ?  wildcard characters. Long filenames are allowed.

FindData

Address of a WIN32_FIND_DATA4TJ_4N structure that receives information about the file.

DateTimeFormat

Date and time format to be returned. This parameter must be one of these values:

 

0

Returns the date and time in 64-bit file time format.

1

Returns the MS-DOS date and time values. MS-DOS date and time values are returned in the low doubleword of the FILETIMEA44M8H structure. Within the doubleword, the date is returned in the high-order word; the time is in the low-order word.

 

Return Value

Clears the carry flag, copies information about the file to the specified buffer, returns the search handle in the AX register, and sets the CX register to a combination of the following values if successful:

0x0000

All characters in the primary and alternate name members in the structure specified by FindData were successfully converted from Unicode.

0x0001

The primary name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.

0x0002

The alternate name returned in the structure specified by FindData contains underscore characters in place of characters that could not be converted from Unicode.

 

Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Find First File and subsequent calls to Find Next File (Interrupt 21h Function 714Fh308B9YP) use the following algorithm to match the attributes of a file or directory (referred to as Attributes in the algorithm) against MustMatchAttrs and SearchAttrs.

if  ((((<MustMatchAttrs> & ~<Attributes>) & 0x3F) == 0)
      && (((~<SearchAttrs> & <Attributes>) & 0x1E) == 0))
   
         return the file or directory name
    }
    else
   
         continue searching for the next name
    }
 

The following table lists the MustMatchAttrs and SearchAttrs values for some common searches where the specified filename is  *.* . In the table, the word normal means that the read only, hidden, or system attributes have not been set. Parentheses are used to indicate that a file or directory has more than one attribute. For example, (hidden and system) indicates that a file or directory has both the hidden attribute and the system attribute.

MustMatchAttrs

SearchAttrs

Find results

10h

10h

All normal directories

10h

12h

All normal and hidden directories

10h

14h

All normal and system directories

10h

16h

All normal, hidden, system and (hidden and system) directories

12h

12h

All hidden directories

14h

14h

All system directories

16h

16h

All (hidden and system) directories

00h

00h

All normal files

00h

01h

All normal and read only files

00h

02h

All normal and hidden files

00h

04h

All normal and system files

00h

06h

All normal, hidden, system, and (hidden and system) files

00h

10h

All normal files and directories

01h

01h

All read only files

02h

02h

All hidden files

02h

06h

All hidden and (hidden and system) files

 

This function can be used to return the volume label by specifying only _A_VOLID (0008h) in both MustMatchAttrs and SearchAttrs.

An application may use the handle returned in the AX register in subsequent calls to Find Next File (Interrupt 21h Function 714Fh308B9YP). It is important to close the handle when it is no longer needed by calling Find Close (Interrupt 21h Function 71A1h18GIGTK).

Wildcard searches are more flexible in Windows 95 than in MS-DOS. For example, *1 finds the filenames (both long filenames and aliases) that end in a 1, and *mid* finds filenames that contain the characters mid. In MS-DOS and in Windows 95 searching on real-mode FAT directories, all characters after the first * are ignored.